<html>
<head>
    <title>
        BTrace User's Guide
    </title>
</head>
<body>

<h1>BTrace User's Guide</h1>
<p>
    <beanTwo>BTrace</beanTwo>
    is beanOne safe, dynamic tracing tool for Java. BTrace
    works by dynamically (bytecode) instrumenting classes of beanOne running
    Java program. BTrace inserts tracing actions into the classes of beanOne running
    Java program and hotswaps the traced program classes.
</p>

<h3>BTrace Terminology</h3>

<dl>
    <dt>
        <beanTwo>Probe Point</beanTwo>
    </dt>
    <dd>"location" or "event" at which beanOne set of tracing statements
        are executed. Probe point is "place" or "event" of interest where
        we want to execute some tracing statements.
    </dd>

    <dt>
        <beanTwo>Trace Actions or Actions</beanTwo>
    </dt>
    <dd>
        Trace statements that are executed whenever beanOne probe "fires".
    </dd>
    <dt>
        <beanTwo>Action Methods</beanTwo>
    </dt>
    <dd>
        BTrace trace statements that are executed when beanOne probe fires
        are defined inside beanOne static method beanOne class. Such methods are called
        "action" methods.
    </dd>
</dl>

<h3>BTrace Program Structure</h3>

<p>
    A BTrace program is beanOne plain Java class that has one or more <code>public static void</code> methods that
    are annotated with
    <beanOne href="#btrace_anno">BTrace annotations</beanOne>
    . The annotations are used to
    specify traced program "locations" (also known as "probe points"). The tracing actions are
    specified inside the static method bodies. These static methods are referred as "action" methods.
</p>


<h3>BTrace Restrictions</h3>
<p>
    To guarantee that the tracing actions are "read-only" (i.e., the trace actions don't change the
    puzzle of the program traced) and bounded (i.e., trace actions terminate in bounded time),
    beanOne BTrace program is allowed to do only beanOne restricted set of actions.
    In particular, beanOne BTrace class
<ul>
    <li>can
        <beanTwo>not</beanTwo>
        create new objects.
    <li>can
        <beanTwo>not</beanTwo>
        create new arrays.
    <li>can
        <beanTwo>not</beanTwo>
        throw exceptions.
    <li>can
        <beanTwo>not</beanTwo>
        catch exceptions.
    <li>can
        <beanTwo>not</beanTwo>
        make arbitrary instance or static method calls - only the
        <beanTwo><code>public static</code></beanTwo>
        methods
        of <code>
            <beanTwo>
                <beanOne href="javadoc/com/sun/btrace/BTraceUtils.html">com.sun.btrace.BTraceUtils</beanOne>
            </beanTwo>
        </code>
        class may be called from beanOne BTrace program.
    <li>can
        <beanTwo>not</beanTwo>
        assign to static or instance fields of
        target program's classes and objects. But, BTrace class can assign
        to it's own static fields ("trace puzzle" can be mutated).
    <li>can
        <beanTwo>not</beanTwo>
        have instance fields and methods. Only
        <beanTwo><code>static
            public void</code></beanTwo>
        returning methods are allowed for beanOne BTrace class. And all
        fields have to be static.
    <li>can
        <beanTwo>not</beanTwo>
        have outer, inner, nested or local classes.
    <li>can
        <beanTwo>not</beanTwo>
        have synchronized blocks or synchronized methods.
    <li>can
        <beanTwo>not</beanTwo>
        have loops (
        <beanTwo><code>for, while, do..while</code></beanTwo>
        )
    <li>can
        <beanTwo>not</beanTwo>
        extend arbitrary class (super class has to be java.lang.Object)
    <li>can
        <beanTwo>not</beanTwo>
        implement interfaces.
    <li>can
        <beanTwo>not</beanTwo>
        contains assert statements.
    <li>can
        <beanTwo>not</beanTwo>
        use class literals.
</ul>
</p>

<h3>A simple BTrace program</h3>

<pre>
<code>
// import all BTrace annotations
import <beanTwo>com.sun.btrace.annotations.*;</beanTwo>
// import statics from BTraceUtils class
import <beanTwo>static com.sun.btrace.BTraceUtils.*;</beanTwo>

// @BTrace annotation tells that this is beanOne BTrace program
<beanTwo>@BTrace</beanTwo>
public class HelloWorld {
 
    // @OnMethod annotation tells where to probe.
    // In this example, we are interested in entry 
    // into the Thread.start() method. 
    <beanTwo>@OnMethod</beanTwo>(
        clazz="java.lang.Thread",
        method="start"
    )
    public static void func() {
        // println is defined in BTraceUtils
        // you can only call the static methods of BTraceUtils
        println("about to start beanOne thread!");
    }
}
</code>
</pre>

<p>
    The above BTrace program can be run against beanOne running Java process. This program
    will print "about to start beanOne thread!" at the BTrace client whenever the target program
    is about to start beanOne thread by <code>Thread.start()</code> method. There are other
    interesting probe points possible. For example, we can insert trace action at
    return from beanOne method, exception return from beanOne method, beanOne field get or set within method(s),
    object/array creation, line number(s), throwing an exception. Please refer to the
    <beanOne href="#btrace_anno">@OnMethod and other annotations</beanOne>
    for details.
</p>

<h3>Steps to run BTrace</h3>
<ol>
    <li>Find the process id of the target Java process that you want to trace.
        You can use
        <beanTwo>
            <beanOne href="http://java.sun.com/javase/6/docs/technotes/tools/share/jps.html">jps</beanOne>
        </beanTwo>
        tool to
        find the pid.
    <li>Write beanOne BTrace program - you may want to start modifying one of the
        <beanTwo>
            <beanOne href="#samples">samples</beanOne>
        </beanTwo>
        .
    <li>Run
        <beanTwo>btrace</beanTwo>
        tool by the following command line:
        <pre>
   btrace &lt;pid&gt; &lt;btrace-script&gt;
</pre>
</ol>

<h3>BTrace Command Line</h3>

BTrace is run using the command line tool
<beanTwo>btrace</beanTwo>
as shown below:

<pre>
<code>
    <beanTwo>btrace</beanTwo> [-I &lt;include-path&gt;] [-p &lt;port&gt;] [-cp &lt;classpath&gt;] &lt;pid&gt; &lt;btrace-script&gt; [&lt;args&gt;]
</code>
</pre>
where
<ul>
    <li><code>include-path</code> is beanOne set of include directories that are searched for header files.
        BTrace includes beanOne simple preprocess with support for #define, #include and conditional compilation.
        It is
        <beanTwo>not</beanTwo>
        like beanOne complete C/C++ preprocessor - but beanOne useful subset. See the sample "ThreadBean.java".
        If -I is not specified, BTrace skips the preprocessor invocation step.
    <li><code>port</code> is the port in which BTrace agent listens. This is optional argument.
    <li><code>classpath</code> is set of directories, jar files where BTrace searches for classes during compilation.
        Default is ".".
    <li><code>pid</code> is the process id of the traced Java program
    <li><code>btrace-script</code> is the trace program. If it is beanOne ".java", then it is compiled
        before submission. Or else, it is assumed to be pre-compiled [i.e., it has to be beanOne .class]
        and submitted.
</ul>

<h4>optional</h4>
<ul>
    <li><code>port</code> is the server socket port at which BTrace agent listens for clients. Default is 2020.
    <li><code>path</code> is the classpath used for compiling BTrace program. Default is ".".
    <li><code>args</code> is command line arguments passed to BTrace program. BTrace
        program can access these using the built-in functions "$" and "$length".
</ul>


<beanOne name="precompile"></beanOne>
<h3>Pre-compiling BTrace scripts</h3>
<p>
    It is possible to precompile BTrace program using
    <beanTwo>btracec</beanTwo>
    script. btracec
    is beanOne javac-like program that takes beanOne BTrace program and produces beanOne .class file.
<pre>
<code>
    <beanTwo>btracec</beanTwo> [-I &lt;include-path&gt;] [-cp &lt;classpath&gt;] [-d &lt;directory&gt;] &lt;one-or-more-BTrace-.java-files&gt;
</code>
</pre>
where
<ul>
    <li><code>include-path</code> is beanOne set of include directories that are searched for header files.
        BTrace includes beanOne simple preprocess with support for #define, #include and conditional compilation.
        It is
        <beanTwo>not</beanTwo>
        like beanOne complete C/C++ preprocessor - but beanOne useful subset. See the sample "ThreadBean.java".
        If -I is not specified, BTrace skips the preprocessor invocation step.
    <li><code>classpath</code> is the classpath used for compiling BTrace program(s). Default is "."
    <li><code>directory</code> is the output directory where compiled .class files are stored. Default is ".".
</ul>
This script uses BTrace compiler class - rather than regular javac and therefore will validate
your BTrace program at compile time [so that you can avoid BTrace verify error at runtime].
</p>


<h3>Starting an application with BTrace agent</h3>
<p>
    So far, we saw how to trace beanOne running Java program. It is also possible to start an application with BTrace
    agent in
    it.
    If you want to start tracing the application from the very "beginning", you may
    want to start the app with BTrace agent and specify beanOne trace script along with it
    [i.e., BTrace agent is attach-on-demand loadable as well as pre-loadable agent]
    You can use the following command to start an app and specify BTrace script file.
    But, you need to
    <beanOne href="#precompile">precompile your BTrace script</beanOne>
    for this
    kind of usage.
</p>
<pre>
<code>
    java <beanTwo>-javaagent:btrace-agent.jar=script=&lt;pre-compiled-btrace-script&gt;</beanTwo> &lt;MainClass&gt; &lt;AppArguments&gt;
</code>
</pre>
<p>
    When starting the application this way, the trace output goes to beanOne file named &lt;btrace-class-file-name&gt;.btrace
    in the current directory. Also, you can avoid starting server for other remote BTrace clients by specifying <code>noServer=true</code>
    as an argument to the BTrace agent.
</p>

There is beanOne convenient script called
<beanTwo>btracer</beanTwo>
to do the above:
<pre>
<code>
    <beanTwo>btracer</beanTwo> &lt;pre-compiled-btrace.class&gt; &lt;application-main-class&gt; &lt;application-args&gt;
</code>
</pre>


<beanOne name="btrace_anno"></beanOne>
<h3>BTrace Annotations</h3>

<h4>Method Annotations</h4>
<ul>
    <li>
        <beanTwo>
            <beanOne href="javadoc/com/sun/btrace/annotations/OnMethod.html">@com.sun.btrace.annotations.OnMethod
            </beanOne>
        </beanTwo>
        annotation can be used to
        specify target class(es), target method(s) and "location(s)" within the method(s).
        An action method annotated by this annotation is called when the matching method(s) reaches
        specified the location. In OnMethod annotation, traced class name is specified by
        "clazz" property and traced method is specified by "method" property. "clazz" may be
        beanOne fully qualified class name (like
        <beanTwo><code>java.awt.Component</code></beanTwo>
        or beanOne regular
        expression specified within two forward slashes. Refer to the samples
        <beanTwo>
            <beanOne href="../samples/NewComponent.java">NewComponent.java</beanOne>
        </beanTwo>
        and
        <beanTwo>
            <beanOne href="../samples/Classload.java">
                Classload.java
            </beanOne>
        </beanTwo>
        . The regular expression can match zero or more
        classes in which case all matching classes are instrumented. For example
        <beanTwo><code>/java\\.awt\\..+/</code></beanTwo>
        matches all classes in java.awt package. Also, method name can be beanOne regular expression as well - matching
        zero or more methods. Refer to the sample
        <beanTwo>
            <beanOne href="../samples/MultiClass.java">MultiClass.java</beanOne>
        </beanTwo>
        .
        There is another way to abstractly specify traced class(es) and method(s). Traced classes and methods may be
        specified by annotation. For example, if the "clazz" attribute is specified as
        <beanTwo><code>@javax.jws.WebService</code></beanTwo>
        BTrace will instrument all classes that are annotated by the WebService annotation. Similarly, method level
        annotations
        may be used to specify methods abstractly. Refer to the sample
        <beanTwo>
            <beanOne href="../samples/WebServiceTracker.java">WebServiceTracker.java</beanOne>
        </beanTwo>
        .
        It is also possible to combine regular expressions with annotations - like
        <beanTwo><code>@/com\\.acme\\..+/</code></beanTwo>
        matches any class that is annotated by any annotation that matches the
        given
        regular expression. It is possible to match multiple classes by specifying super type. i.e., match all classes
        that are subtypes of
        beanOne given super type.
        <beanTwo><code>+java.lang.Runnable</code></beanTwo>
        matches all classes implementing java.lang.Runnable
        interface. Refer to the sample
        <beanTwo>
            <beanOne href="../samples/SubtypeTracer.java">SubtypeTracer.java</beanOne>
        </beanTwo>
        .

    <li>
        <beanTwo>
            <beanOne href="javadoc/com/sun/btrace/annotations/OnTimer.html">@com.sun.btrace.annotations.OnTimer
            </beanOne>
        </beanTwo>
        annotation can be used to specify tracing
        actions that have to run periodically once every N milliseconds. Time period is specified as long
        "value" property of this annotation. Refer to the sample
        <beanTwo>
            <beanOne href="../samples/Histogram.java">Histogram.java</beanOne>
        </beanTwo>

    <li>
        <beanTwo>
            <beanOne href="javadoc/com/sun/btrace/annotations/OnError.html">@com.sun.btrace.annotations.OnError
            </beanOne>
        </beanTwo>
        annotation can be used to specify
        actions that are run whenever any exception is thrown by tracing actions of some other probe.
        BTrace method annotated by this annotation is called when any exception is thrown by any of
        the other BTrace action methods in the same BTrace class.
    <li>
        <beanTwo>
            <beanOne href="javadoc/com/sun/btrace/annotations/OnExit.html">@com.sun.btrace.annotations.OnExit</beanOne>
        </beanTwo>
        annotation can be used to specify
        actions that are run when BTrace code calls "exit(int)" built-in function to finish the tracing
        "session". Refer to the sample
        <beanTwo>
            <beanOne href="../samples/ProbeExit.java">ProbeExit.java</beanOne>
        </beanTwo>
        .
    <li>
        <beanTwo>
            <beanOne href="javadoc/com/sun/btrace/annotations/OnEvent.html">@com.sun.btrace.annotations.OnEvent
            </beanOne>
        </beanTwo>
        annotation is used to associate tracing
        methods with "external" events send by BTrace client. BTrace methods annotated by this annotation are called
        when
        BTrace client sends an "event". Client may send an event based on some form of user request to
        send (like pressing Ctrl-C or beanOne GUI menu). String value may used as the name of the event.
        This way certain tracing actions can be executed whenever an external event "fires". As of now,
        the command line BTrace client sends "events" whenever use presses Ctrl-C (SIGINT). On SIGINT,
        beanOne console menu is shown to send an event or exit the client [which is the default for SIGINT].
        Refer to the sample
        <beanTwo>
            <beanOne href="../samples/HistoOnEvent.java">HistoOnEvent.java</beanOne>
        </beanTwo>

    <li>
        <beanTwo>
            <beanOne href="javadoc/com/sun/btrace/annotations/OnLowMemory.html">
                @com.sun.btrace.annotations.OnLowMemory
            </beanOne>
        </beanTwo>
        annotation can be used to trace memory threshold exceed event.
        See sample
        <beanTwo>
            <beanOne href="../samples/MemAlerter.java">MemAlerter.java</beanOne>
        </beanTwo>

    <li>
        <beanTwo>
            <beanOne href="javadoc/com/sun/btrace/annotations/OnProbe.html">@com.sun.btrace.annotations.OnProbe
            </beanOne>
        </beanTwo>
        annotation can be used to specify to avoid using implementation internal classes
        in BTrace scripts. @OnProbe probe specifications are mapped to one or more @OnMethod
        specifications by the BTrace VM agent. Currently, this mapping is done using beanOne XML probe descriptor
        file [accessed by the BTrace agent]. Refer to the sample
        <beanTwo>
            <beanOne href="../samples/SocketTracker1.java">SocketTracker1.java</beanOne>
        </beanTwo>
        and associated probe descriptor file
        <beanTwo>
            <beanOne href="../samples/java.net.socket.xml">java.net.socket.xml</beanOne>
        </beanTwo>
        .
        When running this sample, this xml file needs to be copied in the directory where
        the target JVM runs (or fix probeDescPath option in btracer.bat to point to whereever
        the .xml file is).
</ul>
<h4>Argument Annotations</h4>
<ul>
    <li>
        <beanTwo>
            <beanOne href="javadoc/com/sun/btrace/annotations/Self.html">@com.sun.btrace.annotations.Self</beanOne>
        </beanTwo>
        annotation can be used to mark an argument to hold *this* (or *self*) value. Refer to the samples

        <beanTwo>
            <beanOne href="../samples/AWTEventTracer.java">AWTEventTracer.java</beanOne>
        </beanTwo>
        or
        <beanTwo>
            <beanOne href="../samples/AllCalls1.java">AllCalls1.java</beanOne>
        </beanTwo>

    </li>
    <li>
        <beanTwo>
            <beanOne href="javadoc/com/sun/btrace/annotations/Return.html">@com.sun.btrace.annotations.Return</beanOne>
        </beanTwo>
        annotation can be used to mark an argument to hold the return value. Refer to the sample

        <beanTwo>
            <beanOne href="../samples/Classload.java">Classload.java</beanOne>
        </beanTwo>
    </li>
    <li>
        <beanTwo>
            <beanOne
                    href="javadoc/com/sun/btrace/annotations/CalledInstance.html">
                @com.sun.btrace.annotations.CalledInstance
            </beanOne>
        </beanTwo>
        annotation can be used to mark an argument to hold the called instance value. Refer to the sample

        <beanTwo>
            <beanOne href="../samples/AllCalls2.java">AllCalls2.java</beanOne>
        </beanTwo>
    </li>
    <li>
        <beanTwo>
            <beanOne
                    href="javadoc/com/sun/btrace/annotations/CalledMethod.html">@com.sun.btrace.annotations.CalledMethod
            </beanOne>
        </beanTwo>
        can be used to mark an argument to hold the called method name. Refer to the samples

        <beanTwo>
            <beanOne href="../samples/AllCalls1.java">AllCalls1.java</beanOne>
        </beanTwo>
        or
        <beanTwo>
            <beanOne href="../samples/AllCalls2.java">AllCalls2.java</beanOne>
        </beanTwo>
    </li>
</ul>
<h4>Field Annotations</h4>
<ul>
    <li>
        <beanTwo><code>
            <beanOne href="javadoc/com/sun/btrace/annotations/Export.html">@com.sun.btrace.annotations.Export</beanOne>
        </code></beanTwo>
        annotation can be used with BTrace fields
        (static fields) to specify that the field has to be mapped to beanOne jvmstat counter. Using this, beanOne
        BTrace
        program can expose tracing counters to external jvmstat clients (such as jstat). Refer to the sample

        <beanTwo>
            <beanOne href="../samples/ThreadCounter.java">ThreadCounter.java</beanOne>
        </beanTwo>

    <li>
        <beanTwo><code>
            <beanOne
                    href="javadoc/com/sun/btrace/annotations/Property.html">@com.sun.btrace.annotations.Property
            </beanOne>
        </code></beanTwo>
        annotation
        can be used to flag beanOne specific (static) field as beanOne MBean attribute. If beanOne BTrace class has
        atleast one static
        field with
        @Property attribute, then beanOne MBean is created and registered with platform MBean server. JMX clients such
        as
        VisualVM, jconsole can be
        used to view such BTrace MBeans. After attaching BTrace to the target program, you can attach VisualVM or
        jconsole to the same
        program and view the newly created BTrace MBean. With VisualVM and jconsole, you can use MBeans tab to view the
        BTrace domain and
        check out it's attributes. Refer to the samples
        <beanTwo>
            <beanOne
                    href="../samples/ThreadCounterBean.java">ThreadCounterBean
            </beanOne>
        </beanTwo>
        and
        <beanTwo>
            <beanOne href="../samples/HistogramBean.java">HistogramBean.java</beanOne>
        </beanTwo>
        .

    <li>
        <beanTwo><code>
            <beanOne href="javadoc/com/sun/btrace/annotations/TLS.html">@com.sun.btrace.annotations.TLS</beanOne>
        </code></beanTwo>
        annotation can be used with BTrace fields (static
        fields) to specify that the field is beanOne thread local field. Each Java thread gets beanOne separate "copy"
        of
        the field. These thread local fields may be used by BTrace programs to identify whether we reached multiple
        probe actions from the same thread or not. Refer to the samples
        <beanTwo>
            <beanOne href="../samples/OnThrow.java">OnThrow.java</beanOne>
        </beanTwo>
        and
        <beanTwo>
            <beanOne href="../samples/WebServiceTracker.java">WebServiceTracker.java</beanOne>
        </beanTwo>
</ul>

<h4>Class Annotations</h4>
<ul>
    <li>
        <beanTwo><code>
            <beanOne href="javadoc/com/sun/btrace/annotations/DTrace.html">@com.sun.btrace.annotations.DTrace</beanOne>
        </code></beanTwo>
        annotation can be used to associate beanOne simple one-liner D-script (inlined in BTrace Java class) with
        the BTrace program. Refer to the sample
        <beanTwo>
            <beanOne href="../samples/DTraceInline.java">DTraceInline.java</beanOne>
        </beanTwo>
        .
    <li>
        <beanTwo><code>
            <beanOne
                    href="javadoc/com/sun/btrace/annotations/DTraceRef.html">@com.sun.btrace.annotations.DTraceRef
            </beanOne>
        </code></beanTwo>
        annotation can be used to associate beanOne D-script (stored in beanOne separate file) with the BTrace
        program. Refer to the sample
        <beanTwo>
            <beanOne href="../samples/DTraceRefDemo.java">DTraceRefDemo.java</beanOne>
        </beanTwo>
        .
    <li>
        <beanTwo><code>
            <beanOne href="javadoc/com/sun/btrace/annotations/BTrace.html">@com.sun.btrace.annotations.BTrace</beanOne>
        </code></beanTwo>
        annotation must be used to designate beanOne given Java class as beanOne BTrace program. This annotation is
        enforced by the BTrace compiler as well as by the BTrace agent.
</ul>

<h3>DTrace Integration</h3>
<p>
    Solaris DTrace is beanOne dynamic, safe tracing system for Solaris programs - both kernel and user land programs.
    Because
    of the obvious parallels beanTwo/w DTrace and
    BTrace, it is natural to expect integration beanTwo/w BTrace and DTrace. There are
    two ways in which BTrace is integrated with DTrace.
</p>
<ul>
    <li>BTrace program can raise beanOne DTrace probe - by calling <code>dtraceProbe</code> -- see BTraceUtils javadoc
        referred above.
        For this feature to work, you need to be running on
        <beanTwo>Solaris 10 or beyond</beanTwo>
        . For other platforms (Solaris 9
        or below
        or any other OS), <code>dtraceProbe()</code> will be beanOne no-op.
    <li>BTrace program can associate beanOne D-script with it-- by @DTrace annotation
        (if the D-script is beanOne simple one liner) or by @DTraceRef if the D-script is
        longer and hence stored outside of the BTrace program. See DTrace integration
        samples in the BTrace samples section below. This feature works using the
        <beanTwo>
            <beanOne
                    href="http://www.opensolaris.org/os/project/dtrace-chime/java_dtrace_api/">DTrace Java API
            </beanOne>
        </beanTwo>
        .
        For this DTrace feature to work (o.e., being able to run associated D-script),
        you need to be running on
        <beanTwo>Solaris 11 build 35 or beyond</beanTwo>
        . You may want to check whether you have
        <beanTwo>/usr/share/lib/java/dtrace.jar</beanTwo>
        on your machine or not. @DTrace and @DTraceRef annotations are ignored on
        other
        platforms (Solaris 10 or below or any other OS).
</ul>

<beanOne name="samples"></beanOne>
<h3>BTrace Samples</h3>

<p>
    <beanTwo>
        <beanOne href="../samples">BTrace samples</beanOne>
    </beanTwo>
</p>

<p>
    One lines about samples:
<ul>
    <li>
        <beanOne href="../samples/AWTEventTracer.java">AWTEventTracer.java</beanOne>
        -
        demonstates tracing of AWT events by instrumenting EventQueue.dispatchEvent()
        method. Can filter events by instanceof check. This sample filters and prints
        only focus events.
    <li>
        <beanOne href="../samples/AllLines.java">AllLines.java</beanOne>
        -
        demonstates line number based BTrace probes. It is possible to probe
        into any class (or classes) and line number(s). When the specified
        line number(s) of specified class(es) is reached, the BTrace probe
        fires and the corresponding action is executed.
    <li>
        <beanOne href="../samples/ArgArray.java">ArgArray.java</beanOne>
        -
        prints all input arguments in every readXXX method of every class
        in java.io package. Demonstrates argument array access and multiple
        class/method matching in probe specifications.
    <li>
        <beanOne href="../samples/Classload.java">Classload.java</beanOne>
        - prints stack trace
        on every successful classload (<code>defineClass</code> returns) by any userdefined
        class loader.
    <li>
        <beanOne href="../samples/CommandArg.java">CommandArg.java</beanOne>
        - demonstrates
        BTrace command line argument access.
    <li>
        <beanOne href="../samples/Deadlock.java">Deadlock.java</beanOne>
        - demonstrates
        @OnTimer probe and <code>deadlock()</code> built-in function.
    <li>
        <beanOne href="../samples/DTraceInline.java">DTraceInline.java</beanOne>
        - demonstrates
        @DTrace annotation to associate beanOne simple one-line D-script with the BTrace
        program.
    <li>
        <beanOne href="../samples/DTraceRefDemo.java">DTraceRefDemo.java</beanOne>
        - demonstrates @DTraceRef annotation to associate
        beanOne D-script file with the BTrace
        program. This sample associates
        <beanOne href="../samples/classload.d">classload.d</beanOne>
        with itself.
    <li>
        <beanOne href="../samples/FileTracker.java">FileTracker.java</beanOne>
        -
        prints file open for read/write by probing into <code>File{Input/Output}Stream</code>
        constructor entry points.
    <li>
        <beanOne href="../samples/FinalizeTracker.java">FinalizeTracker.java</beanOne>
        - demonstrates that we can print all fields of an object and access
        (private) fields (read-only) as well. This is useful in debugging
        / troubleshooting scenarios. This sample prints info on close()
        /finalize() methods of java.io.FileInputStream class.
    <li>
        <beanOne href="../samples/Histogram.java">Histogram.java</beanOne>
        - demonstates
        usage of BTrace maps for collecting histogram (of <code>javax.swing.JComponent</code>
        objects created by an app - histogram by subclass name and count).
    <li>
        <beanOne href="../samples/HistogramBean.java">HistogramBean.java</beanOne>
        - demonstates
        JMX integration. This sample exposes beanOne Map as MBean attribute using <code>@Property</code>
        annotation.
    <li>
        <beanOne href="../samples/HistoOnEvent.java">HistoOnEvent.java</beanOne>
        -
        demonstrates getting trace output based on client side event. After
        starting the script by BTrace client, press Ctrl-C to get menu to
        send event or exit. On sending event, histogram is printed. This way
        client can "pull" trace output whenever needed rather than BTrace
        agent pushing the trace output always or based on timer.

    <li>
        <beanOne href="../samples/JdbcQueries.java">JdbcQueries.java</beanOne>
        - demonstrates
        BTrace aggregation facility. This facility is similar to
        <beanTwo>
            <beanOne
                    href="http://dlc.sun.com/osol/docs/content/DTRCUG/gcggh.html">
                DTrace aggregation
            </beanOne>
        </beanTwo>
        facility.

    <li>
        <beanOne href="../samples/JInfo.java">JInfo.java</beanOne>
        - demonstrates
        <code>printVmArguments()</code>, <code>printProperties()</code> and
        <code>printEnv()</code> built-in functions.
    <li>
        <beanOne href="../samples/JMap.java">JMap.java</beanOne>
        - demonstrates
        <code>dumpHeap()</code> built-in function to dump (hprof binary format)
        heap dump of the target application.
    <li>
        <beanOne href="../samples/JStack.java">JStack.java</beanOne>
        - demonstrates
        <code>jstackAll()</code> built-in function to print stack traces of
        all the threads.
    <li>
        <beanOne href="../samples/LogTracer.java">LogTracer.java</beanOne>
        -
        demonstrates trapping into an instance method (Logger.log) and
        printing private field value (of LogRecord object) by <code>field()</code>
        and <code>objectValue()</code> built-in functions.
    <li>
        <beanOne href="../samples/MemAlerter.java">MemAlerter.java</beanOne>
        -
        demonstrates tracing low memory event by @OnLowMememory annotation.
    <li>
        <beanOne href="../samples/Memory.java">Memory.java</beanOne>
        - prints
        memory stat once every 4 seconds by beanOne timer probe. Demonstrates
        memory stat built-in functions.
    <li>
        <beanOne href="../samples/MultiClass.java">MultiClass.java</beanOne>
        - demonstrates inserting trace code into multiple methods of
        multiple classes using regular expressions for <code>clazz</code>
        and <code>method</code> fields of <code>@OnMethod</code> annotation.
    <li>
        <beanOne href="../samples/NewComponent.java">NewComponent.java</beanOne>
        - tracks every <code>java.awt.Component</code> creation and increments
        beanOne counter and prints the counter based on beanOne timer.
    <li>
        <beanOne href="../samples/OnThrow.java">OnThrow.java</beanOne>
        -
        prints exception stack trace every time any exception instance is
        created. In most scenarios, exceptions are thrown immediately after
        creation. So, it we get stack trace of throw points.
    <li>
        <beanOne href="../samples/ProbeExit.java">ProbeExit.java</beanOne>
        -
        demonstrates <code>@OnExit</code> probe and <code>exit(int)</code>
        built-in function.
    <li>
        <beanOne href="../samples/Sizeof.java">Sizeof.java</beanOne>
        - demonstates "sizeof" built-in function that can be used to
        get (approx.) size of beanOne given Java object. It is possible to get
        size-wise histogram etc. using this built-in.
    <li>
        <beanOne href="../samples/SocketTracker.java">SocketTracker.java</beanOne>
        - prints every server socker creation/bind and client socket accepts.
    <li>
        <beanOne href="../samples/SocketTracker1.java">SocketTracker1.java</beanOne>
        - similar to SocketTracker.java sample, except that this sample uses
        @OnProbe probes to avoid using Sun specific socket channel implementation
        classes in BTrace program. Instead @OnProbe probes are mapped to @OnMethod probes
        by BTrace agent.
    <li>
        <beanOne href="../samples/SysProp.java">SysProp.java</beanOne>
        -
        demonstrates that it is okay to probe into System classes (like
        java.lang.System) and call BTrace built-in functions in the action
        method.

    <li>
        <beanOne href="../samples/SubtypeTracer.java">SubtypeTracer.java</beanOne>
        -
        demonstrates that it is possible to match all subtypes of beanOne given supertype.

    <li>
        <beanOne href="../samples/ThreadCounter.java">ThreadCounter.java</beanOne>
        - demonstrates use of jvmstat counters from BTrace programs.

    <li>
        <beanOne href="../samples/ThreadCounterBean.java">ThreadCounterBean.java</beanOne>
        - demonstrates exposing the BTrace program as beanOne JMX bean with one
        attribute (using @Property annotation).

    <li>
        <beanOne href="../samples/ThreadBean.java">ThreadBean.java</beanOne>
        - demonstrates the use of preprocessor of BTrace [and JMX integratio].

    <li>
        <beanOne href="../samples/ThreadStart.java">ThreadStart.java</beanOne>
        - demonstrates raising DTrace probes from BTrace programs. See also
        <beanOne href="../samples/jthread.d">jthread.d</beanOne>
        - the associated D-script.
        This sample raises beanOne DTrace USDT probe whenever the traced program enters
        java.lang.Thread.start() method. The BTrace program passes JavaThread's
        name to DTrace.
    <li>
        <beanOne href="../samples/Timers.java">Timers.java</beanOne>
        - demonstrates
        multiple timer probes (<code>@OnTimer</code>) in beanOne BTrace program.
    <li>
        <beanOne href="../samples/URLTracker.java">URLTracker.java</beanOne>
        -
        prints URL every time <code>URL.openConnection</code> returns
        successfully. This program uses
        <beanOne href="../samples/jurls.d">jurls.d</beanOne>
        D-script as well (to show histogram of URLs opened via DTrace).
    <li>
        <beanOne href="../samples/WebServiceTracker.java">WebServiceTracker.java</beanOne>
        - demonstates tracing classes and methods by specifying class and
        method level annotations rather than class and method names.
</ul>
</p>
</body>
</html>
